Qualcomm Technologies, Inc. PMIC thermal monitor ADC driver (ADC_TM)

PMIC thermal monitoring (TM) provides interface to thermal clients
to set temperature thresholds and receive notification when the thresholds
are crossed. A 16 bit ADC is used for measurements. The driver is part
of the sysfs thermal framework that provides support to read the trip
points, set threshold for the trip points and enable the trip points.

ADC_TM node

- compatible:
    Usage: required
    Value type: <string>
    Definition: Should contain "qcom,adc-tm5" or "qcom,adc-tm5-iio" for PMIC5 ADC TM device.
            Should contain "qcom,adc-tm7" or "qcom,adc-tm5-iio" for PMIC7 ADC TM device.
            Should contain "qcom,adc-tm-rev2" for PMIC refresh ADC_TM device

- reg:
    Usage: required
    Value type: <u32>
    Definition: ADC_TM base address in the SPMI PMIC register map.

- #address-cells:
    Usage: required
    Value type: <u32>
    Definition: Must be one. Child node 'reg' property should define ADC
            channel number.

- #size-cells:
    Usage: required
    Value type: <u32>
    Definition: Must be zero.

- interrupts:
    Usage: required
    Value type: <prop-encoded-array>
    Definition: Threshold violation interrupt.

- interrupt-names:
    Usage: required
    Value type: <string>
    Definition: Should contain "thr-int-en" for PMIC5 ADC TM driver.

- qcom,decimation:
    Usage: optional
    Value type: <u32>
    Definition: This parameter is used to decrease ADC sampling rate.
            Quicker measurements can be made by reducing decimation ratio.
            For PMIC5 ADC, combined two step decimation values are 250, 420 and 840.
            If property is not found, default value of 840 will be used.

- qcom,avg-samples:
    Usage: optional
    Value type: <u32>
    Definition: Number of samples to be used for measurement.
            Averaging provides the option to obtain a single measurement
            from the ADC that is an average of multiple samples. The value
            selected is 2^(value).
            Valid values are: 1, 2, 4, 8, 16
            If property is not found, 1 sample will be used.

- #thermal-sensor-cells:
    Usage: optional
    Value type: <u32>
    Definition: Should be 1. See thermal.txt for a description.

- io-channels:
    Usage: Required
    Value type: <phandle u32>
    Definition: The phandle of the iio provider.

Channel node properties:

- reg:
    Usage: required
    Value type: <u32>
    Definition: For PMIC5, ADC channel number.
            See include/dt-bindings/iio/qcom,spmi-vadc.h
            For PMIC7, ADC virtual channel number, made by combining SID of
            PMIC having the channel and actual ADC channel number.
            See files in include/dt-bindings/iio/.

- qcom,pre-scaling:
    Usage: optional
    Value type: <u32 array>
    Definition: Used for scaling the channel input signal before the signal is
            fed to VADC. The configuration for this node is to know the
            pre-determined ratio and use it for post scaling. Select one from
            the following options.
            <1 1>, <1 3>, <1 4>, <1 6>, <1 20>, <1 8>, <10 81>, <1 10>
            If property is not found default value depending on chip will be used.

- qcom,decimation:
    Usage: optional, used as channel property only for PMIC7
    Value type: <u32>
    Definition: This parameter is used to decrease ADC sampling rate.
            Quicker measurements can be made by reducing decimation ratio.
            For PMIC7 ADC, combined two step decimation values are 85, 340 and 1360.
            If property is not found, default value of 1360 will be used.

- qcom,avg-samples:
    Usage: optional, used as channel property only for PMIC7
    Value type: <u32>
    Definition: Number of samples to be used for measurement.
            Averaging provides the option to obtain a single measurement
            from the ADC that is an average of multiple samples.
            Valid values are: 1, 2, 4, 8, 16
            If property is not found, 1 sample will be used.

- qcom,kernel-client:
    Usage: optional
    Value type: <empty>
    Definition: Used to indicate if the client for this channel is not the
            thermal framework. Non-thermal clients use a different set of
            APIs to configure their channels. In addition, the reverse scaling function
            needs to be specified for them. If property is not found, channel will be
            considered as thermal by default.

- qcom,scale-type:
    Usage: optional
    Value type: <u32>
    Definition: Reverse scaling function used to convert raw ADC code to units
            specific to a given channel.
            Select from the following unsigned int.
            0 : Scaling to convert voltage in uV to raw adc code.

- qcom,ratiometric:
    Usage: optional
    Value type: <empty>
    Definition: Channel calibration type. If this property is specified
            VADC will use the VDD reference (1.875V) and GND for channel
            calibration. If property is not found, channel will be
            calibrated with 0V and 1.25V reference channels, also
            known as absolute calibration.

- qcom,hw-settle-time:
    Usage: optional
    Value type: <u32>
    Definition: Time between AMUX getting configured and the ADC starting
            conversion.
            For PMIC5, delay = 15us for value 0,
                        100us * (value) for values 0 < value < 11, and
                        2ms * (value - 10) otherwise.
            Valid values are: 15, 100, 200, 300, 400, 500, 600, 700, 1,
            2, 4, 8, 16, 32, 64, 128 ms
            For PMIC7, valid values are: 15, 100, 200, 300, 400, 500, 600,
            700, 1000, 2000, 4000, 8000, 16000, 32000, 64000, 128000 us.
            If property is not found, channel will use 15us.

Example:

        /* ADC_TM node */
        pmic_adc_tm: adc_tm@3500 {
                compatible = "qcom,adc-tm5";
                reg = <0x3500 0x100>;
                interrupts = <0x0 0x35 0x0 IRQ_TYPE_EDGE_RISING>;
                interrupt-names = "thr-int-en";
                #address-cells = <1>;
                #size-cells = <0>;
                #thermal-sensor-cells = <1>;
                io-channels = <&pmic_vadc ADC_AMUX_THM2_PU2>;

                /* Channel node */
                skin_msm_therm {
                        reg = <ADC_AMUX_THM2_PU2>;
                        qcom,ratiometric;
                        qcom,hw-settle-time = <200>;
                };
        };

        /* Adding thermal zone to register with of_thermal */
        &thermal_zones {
                wp-therm {
                        polling-delay-passive = <0>;
                        polling-delay = <0>;
                        thermal-governor = "user_space";
                        thermal-sensors = <&pmic_adc_tm ADC_AMUX_THM2_PU2>;
                        trips {
                                active-config0 {
                                        temperature = <125000>;
                                        hysteresis = <1000>;
                                        type = "passive";
                                };
                        };
                };
        };
